<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Tree and List Widget Overview</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
<link rel="home" href="index.html" title="GTK+ Reference Manual">
<link rel="up" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
<link rel="prev" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
<link rel="next" href="GtkTreeModel.html" title="GtkTreeModel">
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="part" href="gtk.html" title="Part I. GTK+ Overview">
<link rel="part" href="gtkbase.html" title="Part II. GTK+ Core Reference">
<link rel="part" href="gtkobjects.html" title="Part III. GTK+ Widgets and Objects">
<link rel="chapter" href="ch01.html" title="Object Hierarchy">
<link rel="chapter" href="ch02.html" title="Widget Gallery">
<link rel="chapter" href="WindowWidgets.html" title="Windows">
<link rel="chapter" href="DisplayWidgets.html" title="Display Widgets">
<link rel="chapter" href="ButtonWidgets.html" title="Buttons and Toggles">
<link rel="chapter" href="NumericEntry.html" title="Numeric/Text Data Entry">
<link rel="chapter" href="TextWidgetObjects.html" title="Multiline Text Editor">
<link rel="chapter" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
<link rel="chapter" href="MenusAndCombos.html" title="Menus, Combo Box, Toolbar">
<link rel="chapter" href="Actions.html" title="Action-based menus and toolbars">
<link rel="chapter" href="SelectorWidgets.html" title="Selectors (File/Font/Color/Input Devices)">
<link rel="chapter" href="LayoutContainers.html" title="Layout Containers">
<link rel="chapter" href="Ornaments.html" title="Ornaments">
<link rel="chapter" href="ScrollingWidgets.html" title="Scrolling">
<link rel="chapter" href="Printing.html" title="Printing">
<link rel="chapter" href="MiscObjects.html" title="Miscellaneous">
<link rel="chapter" href="AbstractObjects.html" title="Abstract Base Classes">
<link rel="chapter" href="PlugSocket.html" title="Cross-process Embedding">
<link rel="chapter" href="SpecialObjects.html" title="Special-purpose features">
<link rel="chapter" href="RecentDocuments.html" title="Recently Used Documents">
<link rel="chapter" href="Builder.html" title="Interface builder">
<link rel="chapter" href="DeprecatedObjects.html" title="Deprecated">
<link rel="part" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="chapter" href="gtk-migrating-checklist.html" title="Migration Checklist">
<link rel="chapter" href="gtk-migrating-GtkFileChooser.html" title="Migrating from GtkFileSelection to GtkFileChooser">
<link rel="chapter" href="gtk-migrating-GtkAction.html" title="Migrating from old menu and toolbar systems to GtkAction">
<link rel="chapter" href="gtk-migrating-GtkComboBox.html" title="Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and GtkComboBoxEntry">
<link rel="chapter" href="gtk-migrating-GtkIconView.html" title="Migrating from GnomeIconList to GtkIconView">
<link rel="chapter" href="gtk-migrating-GtkAboutDialog.html" title="Migrating from GnomeAbout to GtkAboutDialog">
<link rel="chapter" href="gtk-migrating-GtkColorButton.html" title="Migrating from GnomeColorPicker to GtkColorButton">
<link rel="chapter" href="gtk-migrating-GtkAssistant.html" title="Migrating from GnomeDruid to GtkAssistant">
<link rel="chapter" href="gtk-migrating-GtkRecentChooser.html" title="Migrating from EggRecent to GtkRecentChooser">
<link rel="chapter" href="gtk-migrating-GtkLinkButton.html" title="Migrating from GnomeHRef to GtkLinkButton">
<link rel="chapter" href="gtk-migrating-GtkBuilder.html" title="Migrating from libglade to GtkBuilder">
<link rel="chapter" href="gtk-migrating-tooltips.html" title="Migrating from GtkTooltips to GtkTooltip">
<link rel="part" href="pt05.html" title="Part V. GTK+ Tools">
<link rel="glossary" href="glossary.html" title="Glossary">
<link rel="index" href="api-index-full.html" title="Index of all symbols">
<link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
<link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
<link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
<link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
<link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
<link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
<link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
<link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="TreeWidgetObjects.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="TreeWidgetObjects.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ Reference Manual</th>
<td><a accesskey="n" href="GtkTreeModel.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry" lang="en">
<a name="TreeWidget"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">Tree and List Widget Overview</span></h2>
<p>Tree and List Widget Overview — Overview of GtkTreeModel, GtkTreeView, and friends</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1" lang="en">
<a name="id3072528"></a><h2>Overview</h2>
<p>
      To create a tree or list in GTK+, use the <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> interface in
      conjunction with the <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget.  This widget is
      designed around a <em class="firstterm">Model/View/Controller</em>
      design and consists of four major parts:
      </p>
<table class="simplelist" border="0" summary="Simple list">
<tr><td>The tree view widget (<span class="structname">GtkTreeView</span>)</td></tr>
<tr><td>The view column (<span class="structname">GtkTreeViewColumn</span>)</td></tr>
<tr><td>The cell renderers (<span class="structname">GtkCellRenderer</span> etc.)</td></tr>
<tr><td>The model interface (<span class="structname">GtkTreeModel</span>)</td></tr>
</table>
<p>
      The <span class="emphasis"><em>View</em></span> is composed of the first three
	objects, while the last is the <span class="emphasis"><em>Model</em></span>.  One
	of the prime benefits of the MVC design is that multiple views
	can be created of a single model.  For example, a model mapping
	the file system could be created for a file manager.  Many views
	could be created to display various parts of the file system,
	but only one copy need be kept in memory.
    </p>
<p>
        The purpose of the cell renderers is to provide extensibility to the
        widget and to allow multiple ways of rendering the same type of data.
        For example, consider how to render a boolean variable.  Should it
        render it as a string of "True" or "False", "On" or "Off", or should
        it be rendered as a checkbox?
    </p>
</div>
<div class="refsect1" lang="en">
<a name="id3306353"></a><h2>Creating a model</h2>
<p>
      GTK+ provides two simple models that can be used: the <a class="link" href="GtkListStore.html" title="GtkListStore"><span class="type">GtkListStore</span></a>
      and the <a class="link" href="GtkTreeStore.html" title="GtkTreeStore"><span class="type">GtkTreeStore</span></a>.  GtkListStore is used to model list widgets, 
      while the GtkTreeStore models trees.  It is possible to develop a new 
      type of model, but the existing models should be satisfactory for all 
      but the most specialized of situations.  Creating the model is quite 
      simple:
    </p>
<div class="informalexample"><pre class="programlisting">
GtkListStore *store = gtk_list_store_new (2, G_TYPE_STRING, G_TYPE_BOOLEAN);
</pre></div>
<p>
      This creates a list store with two columns: a string column and a boolean
      column.  Typically the 2 is never passed directly like that; usually an
      enum is created wherein the different columns are enumerated, followed by
      a token that represents the total number of columns.  The next example will
      illustrate this, only using a tree store instead of a list store. Creating
      a tree store operates almost exactly the same.
    </p>
<div class="informalexample"><pre class="programlisting">
enum
{
   TITLE_COLUMN,
   AUTHOR_COLUMN,
   CHECKED_COLUMN,
   N_COLUMNS
};

GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS,       /* Total number of columns */
                                          G_TYPE_STRING,   /* Book title              */
                                          G_TYPE_STRING,   /* Author                  */
                                          G_TYPE_BOOLEAN); /* Is checked out?         */
</pre></div>
<p>
      Adding data to the model is done using <a class="link" href="GtkTreeStore.html#gtk-tree-store-set" title="gtk_tree_store_set ()"><code class="function">gtk_tree_store_set()</code></a> or 
      <a class="link" href="GtkListStore.html#gtk-list-store-set" title="gtk_list_store_set ()"><code class="function">gtk_list_store_set()</code></a>, depending upon which sort of model was
      created.  To do this, a <a class="link" href="GtkTreeModel.html#GtkTreeIter" title="GtkTreeIter"><span class="type">GtkTreeIter</span></a> must be acquired.  The iterator 
      points to the location where data will be added.
    </p>
<p>
      Once an iterator has been acquired, <a class="link" href="GtkTreeStore.html#gtk-tree-store-set" title="gtk_tree_store_set ()"><code class="function">gtk_tree_store_set()</code></a> is used to
      apply data to the part of the model that the iterator points to.  
      Consider the following example:
    </p>
<div class="informalexample"><pre class="programlisting">
GtkTreeIter   iter;

gtk_tree_store_append (store, &amp;iter, NULL);  /* Acquire an iterator */

gtk_tree_store_set (store, &amp;iter,
                    TITLE_COLUMN, "The Principle of Reason",
                    AUTHOR_COLUMN, "Martin Heidegger",
                    CHECKED_COLUMN, FALSE,
                    -1);
</pre></div>
<p>
    Notice that the last argument is -1.  This is always done because
    this is a variable-argument function and it needs to know when to stop
    processing arguments.  It can be used to set the data in any or all
    columns in a given row.
  </p>
<p>
    The third argument to <a class="link" href="GtkTreeStore.html#gtk-tree-store-append" title="gtk_tree_store_append ()"><code class="function">gtk_tree_store_append()</code></a> is the parent iterator.  It
    is used to add a row to a GtkTreeStore as a child of an existing row.  This
    means that the new row will only be visible when its parent is visible and
    in its expanded state.  Consider the following example:
  </p>
<div class="informalexample"><pre class="programlisting">
GtkTreeIter iter1;  /* Parent iter */
GtkTreeIter iter2;  /* Child iter  */

gtk_tree_store_append (store, &amp;iter1, NULL);  /* Acquire a top-level iterator */
gtk_tree_store_set (store, &amp;iter1,
                    TITLE_COLUMN, "The Art of Computer Programming",
                    AUTHOR_COLUMN, "Donald E. Knuth",
                    CHECKED_COLUMN, FALSE,
                    -1);

gtk_tree_store_append (store, &amp;iter2, &amp;iter1);  /* Acquire a child iterator */
gtk_tree_store_set (store, &amp;iter2,
                    TITLE_COLUMN, "Volume 1: Fundamental Algorithms",
                    -1);

gtk_tree_store_append (store, &amp;iter2, &amp;iter1);
gtk_tree_store_set (store, &amp;iter2,
                    TITLE_COLUMN, "Volume 2: Seminumerical Algorithms",
                    -1);

gtk_tree_store_append (store, &amp;iter2, &amp;iter1);
gtk_tree_store_set (store, &amp;iter2,
                    TITLE_COLUMN, "Volume 3: Sorting and Searching",
                    -1);
</pre></div>
</div>
<div class="refsect1" lang="en">
<a name="id3192394"></a><h2>Creating the view component</h2>
<p>
      While there are several different models to choose from, there is
      only one view widget to deal with.  It works with either the list
      or the tree store.  Setting up a <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> is not a difficult
      matter.  It needs a <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> to know where to retrieve its data 
      from.
    </p>
<div class="informalexample"><pre class="programlisting">
GtkWidget *tree;

tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
</pre></div>
<div class="refsect2" lang="en">
<a name="id3353246"></a><h3>Columns and cell renderers</h3>
<p>
	Once the <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget has a model, it will need to know how 
        to display the model.  It does this with columns and cell renderers.
      </p>
<p>
        Cell renderers are used to draw the data in the tree model in a
        way.  There are a number of cell renderers that come with GTK+ 2.x,
        including the <a class="link" href="GtkCellRendererText.html" title="GtkCellRendererText"><span class="type">GtkCellRendererText</span></a>, <a class="link" href="GtkCellRendererPixbuf.html" title="GtkCellRendererPixbuf"><span class="type">GtkCellRendererPixbuf</span></a> and
        the <a class="link" href="GtkCellRendererToggle.html" title="GtkCellRendererToggle"><span class="type">GtkCellRendererToggle</span></a>.
        It is relatively easy to write a custom renderer.
      </p>
<p>
        A <a class="link" href="GtkTreeViewColumn.html" title="GtkTreeViewColumn"><span class="type">GtkTreeViewColumn</span></a> is the object that GtkTreeView uses to organize 
        the vertical columns in the tree view.  It needs to know the name of 
        the column to label for the user, what type of cell renderer to use, 
        and which piece of data to retrieve from the model for a given row.
      </p>
<div class="informalexample"><pre class="programlisting">
GtkCellRenderer *renderer;
GtkTreeViewColumn *column;

renderer = gtk_cell_renderer_text_new ();
column = gtk_tree_view_column_new_with_attributes ("Author",
                                                   renderer,
                                                   "text", AUTHOR_COLUMN,
                                                   NULL);
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
</pre></div>
<p>
       At this point, all the steps in creating a displayable tree have been
       covered.  The model is created, data is stored in it, a tree view is
       created and columns are added to it.
      </p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3353330"></a><h3>Selection handling</h3>
<p>
        Most applications will need to not only deal with displaying data, but 
        also receiving input events from users.  To do this, simply get a 
        reference to a selection object and connect to the 
        <a class="link" href="GtkTreeSelection.html#GtkTreeSelection-changed" title='The "changed" signal'><span class="type">"changed"</span></a> signal.
      </p>
<div class="informalexample"><pre class="programlisting">
/* Prototype for selection handler callback */
static void tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data);

/* Setup the selection handler */
GtkTreeSelection *select;

select = gtk_tree_view_get_selection (GTK_TREE_VIEW (tree));
gtk_tree_selection_set_mode (select, GTK_SELECTION_SINGLE);
g_signal_connect (G_OBJECT (select), "changed",
                  G_CALLBACK (tree_selection_changed_cb),
                  NULL);
</pre></div>
<p>
          Then to retrieve data for the row selected:
        </p>
<div class="informalexample"><pre class="programlisting">
static void
tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
{
        GtkTreeIter iter;
        GtkTreeModel *model;
        gchar *author;

        if (gtk_tree_selection_get_selected (selection, &amp;model, &amp;iter))
        {
                gtk_tree_model_get (model, &amp;iter, AUTHOR_COLUMN, &amp;author, -1);

                g_print ("You selected a book by %s\n", author);

                g_free (author);
        }
}
</pre></div>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id3357105"></a><h2>Simple Example</h2>
<p>
      Here is a simple example of using a <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget in context 
      of the other widgets.  It simply creates a simple model and view, 
      and puts them together.  Note that the model is never populated 
      with data — that is left as an exercise for the reader.  
      More information can be found on this in the <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> section.
      </p>
<div class="informalexample"><pre class="programlisting">
enum
{
   TITLE_COLUMN,
   AUTHOR_COLUMN,
   CHECKED_COLUMN,
   N_COLUMNS
};

void
setup_tree (void)
{
   GtkTreeStore *store;
   GtkWidget *tree;
   GtkTreeViewColumn *column;
   GtkCellRenderer *renderer;

   /* Create a model.  We are using the store model for now, though we
    * could use any other GtkTreeModel */
   store = gtk_tree_store_new (N_COLUMNS,
                               G_TYPE_STRING,
                               G_TYPE_STRING,
                               G_TYPE_BOOLEAN);

   /* custom function to fill the model with data */
   populate_tree_model (store);

   /* Create a view */
   tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));

   /* The view now holds a reference.  We can get rid of our own
    * reference */
   g_object_unref (G_OBJECT (store));

   /* Create a cell render and arbitrarily make it red for demonstration
    * purposes */
   renderer = gtk_cell_renderer_text_new ();
   g_object_set (G_OBJECT (renderer),
                 "foreground", "red",
                 NULL);

   /* Create a column, associating the "text" attribute of the
    * cell_renderer to the first column of the model */
   column = gtk_tree_view_column_new_with_attributes ("Author", renderer,
                                                      "text", AUTHOR_COLUMN,
                                                      NULL);

   /* Add the column to the view. */
   gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);

   /* Second column.. title of the book. */
   renderer = gtk_cell_renderer_text_new ();
   column = gtk_tree_view_column_new_with_attributes ("Title",
                                                      renderer,
                                                      "text", TITLE_COLUMN,
                                                      NULL);
   gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);

   /* Last column.. whether a book is checked out. */
   renderer = gtk_cell_renderer_toggle_new ();
   column = gtk_tree_view_column_new_with_attributes ("Checked out",
                                                      renderer,
                                                      "active", CHECKED_COLUMN,
                                                      NULL);
   gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);

   /* Now we can manipulate the view just like any other GTK widget */
   ...
}
      </pre></div>
<p>
    </p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.11</div>
</body>
</html>
